June 2007 



Edition 2007-06-20 

Published by 
Infineon Technologies AG 
81726 Miinchen, Germany 
© Infineon Technologies AG 2007. 

All Rights Reserved. 

Legal Disclaimer 

The information given in this document shall in no event be regarded as a guarantee of conditions or 
characteristics (“Beschaffenheitsgarantie”). With respect to any examples or hints given herein, any typical values 
stated herein and/or any information regarding the application of the device, Infineon Technologies hereby 
disclaims any and all warranties and liabilities of any kind, including without limitation warranties of 
non-infringement of intellectual property rights of any third party. 

Information 

For further information on technology, delivery terms and conditions and prices please contact your nearest 
Infineon Technologies Office (www.infineon.com). 

Warnings 

Due to technical requirements components may contain dangerous substances. For information on the types in 
question please contact your nearest Infineon Technologies Office. 

Infineon Technologies Components may only be used in life-support devices or systems with the express written 
approval of Infineon Technologies, if a failure of such components can reasonably be expected to cause the failure 
of that life-support device or system, or to affect the safety or effectiveness of that device or system. Life support 
devices or systems are intended to be implanted in the human body, or to support and/or maintain and sustain 
and/or protect human life. If they fail, it is reasonable to assume that the health of the user or other persons may 
be endangered. 


'Infineon 


CONFIDENTIAL 


EASY 21653 INCA-IP2 
VoIP IPP Subsystem 


SPINACER IP Phone Infineon IP Phone Software Solution (SIP) 
CONFIDENTIAL 

Revision History: 2007-06-20, Revision 1.1 


Previous Version: 


Page 

Subjects (major changes since last revision) 




















Trademarks 

ABM®, ACE®, AOP®, Arcofi®, ASM®, ASP®, BlueMoon®, BlueNIX®, C166®, DuSLIC®, ELIC®, Epic®, FALC®, 
GEMINAX®, Idee®, INCA®, IOM®, lpat®-2, IPVD®, Isac®, Itac®, IWE®, IWORX®, M-GOLD®, MUSAC®, MuSLIC®, 
OCTALFALC®, OCTAT®, POTSWIRE®, QUADFALC®, QUAT®, SCOUT®, SCT®, SEROCCO®, S-GOLD®, 
S-GOLD®lite, S-GOLD®2, S-GOLD®radio, S-GOLD®3, S-GOLD®3H, SICAT®, SICOFI®, SIDEC®, SIEGET®, 
SLICOFI®, SMARTI®, SOCRATES®, VDSLite®, VINETIC®, lOBaseS® are registered trademarks of Infineon 
Technologies AG. 

ConverGate™, DIGITAPE™, DUALFALC™, EasyPort™, VINAX™, WildPass™, lOBaseV™, lOBaseVX™ are 
trademarks of Infineon Technologies AG. 

Microsoft® and Visio® are registered trademarks of Microsoft Corporation. Linux® is a registered trademark of 
Linus Torvalds. FrameMaker® is a registered trademark of Adobe Systems Incorporated. APOXI® is a registered 
trademark of Comneon GmbH & Co. OHG. PrimeCell®, RealView®, ARM® are registered trademarks of ARM 
Limited. OakDSPCore®, TeakLite® DSP Core, OCEM®are registered trademarks of ParthusCeva Inc. 
IndoorGPS™, GL-20000™, GL-LN-22™ are trademarks of Global Locate. ARM926EJ-S™, ADS™, Multi-ICE™ 
are trademarks of ARM Limited. 


Preliminary User’s Manual 
Programmer’s Reference 


3 


Revision 1.1, 2007-06-20 


'Infineon 


CONFIDENTIAL 


EASY 21653 INCA-IP2 
VoIP IPP Subsystem 


Table of Contents 


Table of Contents 


Table of Contents 4 

List of Figures 6 

List of Tables 7 

Preface 8 

1 Introduction 9 

2 Development Environment Setup 11 

2.1 Compilation 11 

2.2 Support of proc File System 11 

3 Interactions between IFX HAPI and TAPI 12 

4 Driver Interface and its Usage 13 

4.1 Driver Interface 13 

4.2 Driver interface functions 13 

4.2.1 Open the Device Driver 13 

4.2.2 Close the Device Driver 13 

4.2.3 Exchange of Control Information 14 

4.2.4 List of ioctl Commands 14 

4.3 General IFXJHAPI Usage 15 

5 ioctl Commands 17 

5.1 LED Control 17 

5.1.1 IFX_HAPI_LED_ON 17 

5.1.2 I FX_H API LE D O FF 18 

5.1.3 I FX_H APILE DETHCTRL 18 

5.2 Display and Pulse Width Modulator Services 19 

5.2.1 I FX_H AP l_G ET_M AX_RO W_CO LU M N 19 

5.2.2 IFX_HAPI_GET_CURSOR_POS 20 

5.2.3 IFX_HAPI_DISPLAY_CLEAR 20 

5.2.4 IFX_HAPI_DISPLAY_GOTO 21 

5.2.5 IFX_HAPI_DISPLAY_PRINT 21 

5.2.6 IFX_HAPI_DISPLAY_MOVE_CURSOR 22 

5.2.7 IFX_HAPI_DISPLAY_POWER_CTRL 23 

5.2.8 IFX_HAPI_DISPLAY_SET_CONTRAST 23 

5.2.9 IFX_HAPI_DISPLAY_GET_CONTRAST 24 

5.2.10 IFX_HAPI_DISPLAY_SET_BRIGHTNESS 24 

5.2.11 IFX_HAPI_DISPLAY_GET_BRIGHTNESS 25 

5.3 Keypad and Hook Status Event 26 

5.3.1 IFX_HAPI_GET_PHONE_EVENT 26 

5.4 Miscellaneous 27 

5.4.1 IFX_HAPI_MAP_SCANCODE_TO_DIGIT 27 

6 Type Definition Reference 28 

6.1 Basic Type Definitions 28 

6.1.1 int8 28 

6.1.2 uint8 28 

6.1.3 inti 6 28 

6.1.4 uintl 6 29 

6.1.5 int32 29 


Preliminary User’s Manual 
Programmer’s Reference 


Revision 1.1, 2007-06-20 


'Infineon 


CONFIDENTIAL 


EASY 21653 INCA-IP2 
VoIP IPP Subsystem 


Table of Contents 


6.1.6 uint32 29 

6.1.7 char8 29 

6.1.8 uchar8 30 

6.2 Constants 30 

6.3 Structures 31 

6.3.1 x_IFX_HAPI_LEDEthCtrl 31 

6.3.2 x_IFX_HAPI_MaxRowColumn 32 

6.3.3 x_IFX_HAPI_CursorPositon 32 

6.3.4 x_IFX_HAPI_DisplayGoTo 33 

6.3.5 x_IFX_HAPI_DisplayPrint 33 

6.3.6 x_IFX_HAPI_PhoneEvent 34 

6.3.7 x_l FX_HAPI_Keyl nfo 34 

6.3.8 x_IFX_HAPI_CodeToDigit 35 

References 36 


Preliminary User’s Manual 
Programmer’s Reference 


5 


Revision 1.1, 2007-06-20 


EASY 21653 INCA-IP2 
VoIP IPP Subsystem 



CONFIDENTIAL List of Figures 

List of Figures 


Figure 1 I FX_H API Interface 10 


Preliminary User’s Manual 
Programmer’s Reference 


6 


Revision 


, 2007-06-20 


7 £• EASY 21653 INCA-IP2 

Infineon VolPIPP Subsystem 


CONFIDENTIAL List of Tables 

List of Tables 

Table 1 Linux® Compiler Flags 11 

Table 2 Mapping of Scan Code to DTMF Digits 12 

Table 3 Driver interface 13 

Table 4 IFXJHAPI Commands 14 

Table 5 Constants 30 

Table 6 Structures used 31 


Preliminary User’s Manual 7 Revision 1.1, 2007-06-20 

Programmer’s Reference 



EASY 21653 INCA-IP2 
VoIP IPP Subsystem 


CONFIDENTIAL 


Preface 


Preface 

This manual is a Programmer's Reference manual for the IFXJHAPI for SPINACER IP Phone that uses the INCA- 
IP2 chip. 

Audience 

This manual makes it easier for the programmers and the developers to enhance features of IFXJHAPI for their 
own products based on their specific requirements. 

Related Documentation 

Additional documentation related to IFXJHAPI is available. This includes: 

1. SPINACER VoIP IP Phone Subsystem User’s Manual Software Description (UMPR) 

2. SPINACER VoIP IP Phone Subsystem Phone Application User’s Manual Module Description (PA UMMD) 

Organization of the Document 

IFXJHAPI UMPR comprises the following chapters: 

• Introduction 

• Development Environment Setup 

• Interactions between IFX_HAPI and TAPI 

• Driver Interface and its Usage 

• ioctl Commands 

• Type Definition Reference 
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Introduction 


This chapter gives an overview of VoIP IP Phone Subsystem and an overview of IFXJHAPI interface. 

Overview of VoIP IP Phone Subsystem 

The VoIP Subsystem provides the complete VoIP functionality for a system package. The VoIP subsystem is of 
two types - the VoIP IP Phone subsystem and the VoIP Gateway Subsystem. The VoIP IP Phone subsystem goes 
into the IP Phone system package and the VoIP Gateway subsystem goes into both the VoIP Router and the xDSL 
GW system packages. In general, the VoIP subsystem consists of two major components: 

• Application 

• VoIP Library 

The Applications are of two types - the Phone Application and the Gateway Application. The Phone Application 
takes care of the application requirements for the IP Phone and the GW application takes care of the requirements 
arising out of VRT and xDSL GWs. The VoIP Library is a software library that contains the signaling protocol (SIP 
Toolkit), the media protocol (RTP) and the configuration modules. While the VoIP Library is common to all the 
system packages, the applications act as the differerentiators. 

Overview of IFXHAPI Interface 

This document describes the High-level Application Programmer's Interface (HAPI) that provides general phone 
driver services for voice applications. The IFXJHAPI provides applications a common interface for the use of all 
the non voice related devices on the board like LED, keypad, display, hookswitch, and also interacts with TAPI 
(Telephony Application Programmer’s Interface) for DTMF services. IFXJHAPI internally makes use of the drivers 
available for the different devices like LED, display, and keypad. 

TAPI is a software layer used to control telephony features for Infineon VoIP related products. It provides voice 
related functionalities like AFE control, RTP functionalities, Jitter Buffer etc. 

IFXJHAPI encapsulates the device drivers in the INCA-IP2 phone by using the Kernel APIs that are exported by 
the following drivers: 

1. LED Matrix driver 

2. Keypad driver 

3. Pulse Width Modulator driver 

4. SSC driver for display 

Note: IFX HAPI is compatible only with Linux® OS. 

To get the complete device driver API specification refer to [1], to get the TAPI Specification refer to [4], and to 
get the device description refer to [2]. 

The block diagram depicted in Figure 1 shows the IFXJHAPI interface with the other modules: 
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Figure 1 IFX HAPI Interface 
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2 Development Environment Setup 

This chapter describes how to set up the IFXJHAPI software development environment. 

2.1 Compilation 

This chapter describes how to compile the IFXJHAPI device driver for Linux® (kernel 2.4). 

To retrieve the device driver sources and to obtain the execution rights and directory structure, the following 
command has to be used. It will extract all sources into a directory “hapi”. 

tar -xvzf hapi. tar. gz 

Prerequisite are the toolchain is in place, the path to the cross-compiler and the availability of path to the Linux® 
kernel header files. 

Set the following macros of the make file to the appropriate path: 

• CROSS_COMPILE 

• LINUX_BASE 


Table 1 Linux® Compiler Flags 


Name 

Description 

NODISPLAY_SUPPORT 

By default, HAPI supports character based display. To 
disable this support, define this flag. 

DTMF_TO_TAPI 

Define this flag if DTMF digits have to be passed to TAPI. 
For more details, refer to Interactions between IFX HAPI 
and TAPI. 


2.2 Support of proc File System 

If config_proc_fs is supported, the proc file system reports the status and the version of IFXJHAPI. 

Example - proc File System 

/* To retrieve the version of the HAPI */ 

# cat /proc/driver/hapi/version 
INCA-IP2 HAPI VERSION - 0.1. 1.0 

/* To retrieve the version of the HAPI */ 

# cat /proc/driver/hapi/status 
Hook Switch State: Onhook 
Hookswitch and keypad fifo info: 

Fifo Size: 10 

Max elems queued up: 1 

Elems to be read: 0 
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3 Interactions between IFX_HAPI and TAPI 

HAPI and TAPI being Kernel modules, the interface from IFXJHAPI to TAPI is function based. When HAPI detects 
any DTMF digits, it passes this information to TAPI by using a function iFX_TAPi_Event_Dispatch() 
provided by TAPI. For details on this function, refer to [4]. 

Since Keypad driver provides digits in terms of scan codes, user has to provide the mappings of scan codes for 
the corresponding DTMF digits to IFXJHAPI, using the ioctl IFX_HAPI_MAP_SCANCODE_TO_DIGIT. 

Default mapping of scan code to DTMF digits is given in Table 2. 


Table 2 Mapping of Scan Code to DTMF Digits 


DTMF digit 

Scan code 

0 

0 

1 

1 

2 

2 

3 

3 

4 

4 

5 

5 

6 

6 

7 

10 

8 

11 

9 

12 

* 

13 

# 

14 


Note: Even though Key press is a DTMF digit, the information of the same is reported to the user in terms of scan 
codes, while it is reported to the TAPI as well at the same time. 
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4 Driver Interface and its Usage 

IFXJHAPI is an fd based kernel interface and not a function based interface. 

4.1 Driver Interface 


If config_devfs_fs is supported, device node (/dev/hapi) is created by IFXJHAPI upon insmod of 
IFXJHAPI. 

Table 3 gives the features and the driver interface functions supported by IFXJHAPI: 

Table 3 Driver interface 


Feature 

Driver Interface Function 

Open the Device Driver 

Open (name, flags, type) 

Close the Device Driver 

Close (fd) 

Exchange of Control Information 

ioctl (fd, cmd, arg) 


4.2 Driver interface functions 

Following are the driver interface functions: 

4.2.1 Open the Device Driver 

The IFXJHAPI file descriptor is obtained by opening the pseudo device (/dev/hapi). This file descriptor is used 
to obtain phone events (hook switch status change and keypad events), display messages on the display device, 
and switch the LED’s ON or OFF. 

Prototype 

int open(char *name, int flags, int type); 

Parameters 


Data Type 

Name 

Description 

char8 

name 

/dev/hapi - To open a command file descriptor. 

int32 

flags 

Not used. 

int32 

type 

Not used. 


Return Values 


Data Type 

Description 

int32 

Error Code 


>0 D FD File descriptor 


<0 D ER Error 


4.2.2 Close the Device Driver 

This function closes the IFXJHAPI command file descriptor. 

Prototype 

void close (int fd) ; 
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Data Type 

Name 

Description 

int32 

fd 

IFXJHAPI command file descriptor 


4.2.3 Exchange of Control Information 

IFXJHAPI provides services to the user application through ioctl function. 


Prototype 

int ioctl (int fd, unsigned int cmd, (void*)arg) 


Parameters 


Data Type 

Name 

Description 

int32 

fd 

IFXJHAPI command file descriptor 

uint32 

cmd 

Command 

For the list of commands supported by IFXJHAPI, refer to List of ioctl 
Commands. 

void 

arg 

Argument for the command 


4.2.4 List of ioctl Commands 

Table 4 gives an overview about the IFXJHAPI commands with a short description. A more detailed description 
of every single command is the content of the subsequent chapters. 


Table 4 IFX_HAPI Commands 

LED Services 

IFX HAPI LED ON 

Switches on the LED corresponding to the index. 

IFX HAPI LED OFF 

Switches off the LED corresponding to the index. 

IFX_HAPI_LED_ETH_CTRL 

Defines which LED's are controlled autonomously by the 


Ethernet hardware. 


Display Services 


IFX HAPI GET MAX ROW COLUMN 

Gets the maximum row and maximum column supported by the 
LCD device. 

IFXJHAPIGETCURSORPOS 

Gets the current cursor position on the display. 

IFX HAPI DISPLAY CLEAR 

Clears the display and returns the cursor to the home position. 

IFX HAPI DISPLAY GOTO 

Positions the cursor at the defined place in the display. 

IFX_HAPI_DISPLAY_PRINT 

Prints a string starting at the current cursor position. 

IFX_HAPI_DISPLAY_MOVE_CURSOR 

Moves the cursor left, right, or to the home position. 

IFX HAPI DISPLAY POWER CTRL 

Enables or disables the power down mode. 

IFX HAPI DISPLAY SET CONTRAST 

Sets the contrast of the display by changing the duty cycle of 
the PWM1. 

IFX_HAPI_DISPLAY_GET_CONTRAST 

Gets the currently adjusted pulse width value (duty cycle) for 
contrast. 

IFX HAPI DISPLAY SET BRIGHTNESS 

Controls the brightness of the display by changing the duty 
cycle of the PWM2. 
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Table 4 IFXJHAPI Commands (cont’d) 


IFX_HAPI_DISPLAY_GET_BRIGHTNESS 

Gets the currently adjusted pulse width value (duty cycle) for 
brightness. 

Keypad and Hook Status Event 

IFXHAPIGETPHONEEVENT 

Gets the hook status or the key pressed. 

Miscellaneous 

IFX_HAPI_MAP_SCANCODE_TO_DIGIT 

Provides a mapping of key scan code to digit that is used for 
inband signaling. 


4.3 General IFX_HAPI Usage 

The High-level APIs are used to get telephony events and configure various device specific parameters of the 
INCA-IP2 board. Since IFX_HAPI imports some of the functionalities from TAPI, it must be loaded on the target 
only after loading TAPI. The sequence of loading IFXJHAPI includes: 

• insmod drv_tapi 

• insmod drv_vmmc 

• insmod hapi.o 

Note: Major number and minor number for IFX_HAPI are assigned by the OS. 

The IFXJHAPI is available as a pseudo device. An application intending to use the IFXJHAPI must open this 
device file. To send commands to any device controlled by the IFXJHAPI, the application must issue an ioctl 
with the corresponding command and optional parameters. To receive telephony events, an application must wait 
for exception events using select. 

An application wishing to receive phone events has to block IFXJHAPI command file descriptor. The following 
code provides a sample example for applications to receive phone events (key press event and hook switch 
status). 

#include<ifx_hapi .h> 
void main ( ) 

{ 

uint32 iHapiFd, iSelMax, iRetVal; 
fd_set xExceptFds; 

iHapiFd = open ( "/dev/hapi" , 0) ; 
iSelMax = iHapiFd; 

FD_ZERO ( &xExceptFds ) ; 

FD_SET ( iHapiFd, &xExceptFds ) ; 
do 
{ 

/* sleep till the arrival of an event */ 

iRetVal = select (iSelMax + % NULL, NULL, &xExceptFds, NULL); 
if (iRetVal < 0) 

{ 

/* handle any errors */ 

} 

/* got an event. now get the information */ 

if (ioctl (iHapiFd, IFX_HAPI_GET_PHONE_EVENT , &xPhoneEvent) != 0) 

{ 

printf ( "GET_PHONE_EVENT f ailed\n" ) ; 
break ; 

} 
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5 ioctl Commands 

This chapter describes the iFX_HAPi_Commands by mentioning the return values for each function. The 
organization is as follows: 

5.1 LED Control 

Each bit in the indexLed correspond to bits in the led_reg. For more information on led_reg, refer to [2], The 
following services operate on the command file descriptor (fd): 

5.1.1 IFXHAPILEDON 

Prototype 

Ret = ioctl (fd, IFX_HAPI_LED_ON, indexLED) ; 

Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

IFX_HAPI_LED_ON 

Switches on the LED corresponding to the index 

1 

uint32 

indexLED 

Bit vector specifying which LEDs to switch ON 

Possible values: 

0 H 

■■■H 

FFFFFh 

1 


Return Values 


Data Type 

Description 

int32 

0d 


>0 D 


Example 

indexLED = 0x00001234; 

Ret = ioctl (CmdFd, IFX_HAPI_LED_ON, indexLED) ; 
if (Ret == 0) 

{ 

/* success - all LED's are switched ON */ 

} 

else 

{ 

/* failure - Ret contains LED bits that are not available */ 

} 
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Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

IFXHAPILEDOFF 

Switches off the LED corresponding to the index 

1 

uint32 

indexLED 

Bit vector specifying which LEDs to switch OFF 

Possible values: 

Oh 

1 



FFFFFh 



Return Values 


Data Type 

Description 

int32 

0d 


>o D 


Example 

indexLED = 0x00001234; 

Ret = ioctl (CmdFd, IFX_HAPI_LED_OFF , indexLED); 
if (Ret == 0) 

{ 

/* success - all LED's are switched OFF */ 

} 

else 

{ 

/* failure - Ret contains LED bits that are not available */ 

} 

5.1.3 IFX_HAPI_LED_ETH_CTRL 

Prototype 

Ret = ioctl (fd, IFX_HAPI_LED_ETH_CTRL, pEthCtrl) ; 

Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

IFX_HAPI_LED_ 

ETH_CTRL 

Defines the LEDs that are controlled autonomously by the 
Ethernet hardware 

1 

xlFXHAPILEDE 

thCtrl 

*pEthCtrl 

Pointer to an ethernet control structure 

1 
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Data Type 

Description 

int32 

0d 


>0 D 


Example 

x_IFX_HAPI_LEDEthCtrl xLEDEthCtrl ; 
xLEDEthCtrl . iEthPort = IFX_HAPI_LED_ETHPORT; 

xLEDEthCtrl .ucEthLEDs = IFX_HAPI_LED_ETH_ACT | IFX_HAPI_LED_ETH_TL ; 
Ret = ioctl (CmdFd, IFX_HAPI_LED_ETH_CTRL , &xLEDEthCtrl ) ; 


5.2 Display and Pulse Width Modulator Services 

The following services operate on the command file descriptor: 

5.2.1 IFX_HAPI_GET_MAX_ROW_COLUMN 

Prototype 

Ret = ioctl (fd, IFX_HAPI_GET_MAX_ROW_COLUMN, pxRowColumn); 

Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

1 FX_H AP l_G ET_ 
M AXRO W_CO L 
UMN 

Gets the maximum row and maximum column supported by 
the LCD device 

1 

x_IFX_HAPI_MaxR 

owColumn 

‘pxRowColumn 

Pointer to a structure 

0 


Return Values 


Data Type 

Description 

int32 

0 D OK OK 


<0 D ERR Error 


Example 

x_IFX_HAPI_MaxRowColumn xMaxRowCol ; 

Ret = ioctl (CmdFd, IFX_HAPI_GET_MAX_ROW_COLUMN, &xMaxRowCol ) ; 
MaxRow = xMaxRowCol .ucMaxRow; 

MaxCol = xMaxRowCol .ucMaxCol; 
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Prototype 

Ret = ioctl (fd, IFX_HAPI_GET_CURSOR_POS , pxCursorPos) ; 


Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

1 FX_H AP l_G ET_ 
CURSORPOS 

Gets the current cursor position on the display 

1 

xlFXHAPICurs 

orPositon 

*pxCursorPos 

Pointer to a current cursor position structure 

O 


Return Values 


Data Type 

Description 

int32 

0 D OK OK 


<0 D ERR Error 


Example 

x_IFX_HAPI_CursorPositon xCursorPos ; 

Ret = ioctl (CmdFd, IFX_HAPI_GET_CURSOR_POS, &xCursorPos) ; 
Row = xCursorPos . ucRow; 

Col = xCursorPos .ucColumn; 

5.2.3 IFX_HAPI_DISPLAY_CLEAR 

Prototype 

Ret = ioctl (fd, IFX_HAPI_DISPLAY_CLEAR, 0); 

Parameters 


Data Type 


Name 

Description 

Dir 

uint32 


fd 

Command file descriptor 

1 

uint32 


IFX_HAPI_DISPL 

AYCLEAR 

Clears the display and returns the cursor to the initial 
position (0,0) 

1 


Return Values 


Data Type 

Description 

int32 

0 D OK OK 


<0 D ERR Error 


Example 

Ret = ioctl (CmdFd, IFX_HAPI_DISPLAY_CLEAR, 0); 
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Prototype 

Ret = ioctl (fd, IFX_HAPI_DISPLAY_GOTO, pxDisplayGoTo ) ; 


Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

1 FX_H AP ID 1 SPLAY 
_GOTO 

Positions the cursor at the defined place in the display 

1 

x_IFX_HAPI_Displ 

ayGoTo 

‘pxDisplayGoTo 

Pointer to a structure 

1 


Return Values 


Data Type 

Description 

int32 

0 D OK OK 


<0 D ERR Error 


Example 

x_IFX_HAPI_DisplayGoTo xGoTo 

xGoTo.ucRow =3; /* third row */ 
xGoTo . ucColumn =10; /* tenth column */ 

Ret = ioctl (CmdFd, IFX_HAPI_DISPLAY_GOTO, &xGoTo) ; 

5.2.5 IFX_HAPI_DISPLAY_PRINT 

Prototype 

Ret = ioctl (fd, IFX_HAPI_DISPLAY_PRINT, pxDisplayPrint); 

Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

1 FX_H AP l_D 1 SPLAY 
_GOTO 

Prints a string starting at the current cursor position 

If the end of a line is reached, the cursor moves to the 
beginning of the next line. 

1 

x_IFX_HAPI_Displ 

ayPrint 

‘pxDisplayPrint 

Pointer to a structure 

1 


Return Values 


Data Type 

Description 

int32 

0 D OK OK 


<0 D ERR Error 
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Example 

x_IFX_HAPI_DisplayPrint xDisplayPrint ; 

xDisplayPrint .pszString = Buffer; /* string to be displayed */ 
xDisplayPrint . iNumber = strlen (Buf f er) ; /* string length */ 

Ret = ioctl (CmdFd, IFX_HAPI_DISPLAY_PRINT, &xDisplayPrint) ; 

5.2.6 IFX_HAPI_DISPLAY_MOVE_CURSOR 

Prototype 

Ret = ioctl (fd, IFX_HAPI_DISPLAY_MOVE_CURSOR, iMove) ; 

Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

IFX_HAPI_DISPL 

Moves the cursor accordingly. 

1 


AY_MOVE_CUR 

Moves the cursor left, right, next line column 0, previous line last 



SOR 

column, or to the home position (0,0). On reaching any of the 
edges, the cursor rolls over to the previous or to the next position 
appropriately. 


uint32 

iMove 

Possible values are 

1 



• IFX_HAPI_DISPLAY_LEFT (= 0): 




• IFX_HAPI_DISPLAY_RIGHT 




• I FX_HAP I_DI S PL AY_HOME 

• I FX_HAP I_D I S PL A Y_NEXTL I NE 

• I FX_HAP I_DI S PL AY_ROWHOME 




• IFX_HAPI_DISPLAY_PREVLINE 



Return Values 


Data Type 

Description 

int32 

0 D OK OK 


<0 D ERR Error 


Example 

Ret = ioctl (CmdFd, IFX_HAPI_DISPLAY_MOVE_CURSOR, IFX_HAPI_DISPLAY_RIGHT) ; 
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Prototype 

Ret = ioctl (fd, IFX_HAPI_DISPLAY_POWER_CTRL, bFlag); 


Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

1 FX_H AP ID 1 SPLAY 
POWERCTRL 

Enables or disables the power down mode of the display 
device 

1 

uint32 

bFlag 

0 D IFX_HAPI_FALSE Sets the display to the power down 
mode. 

1 D IFX_HAPI_TRUE Enables the display power again. 



Return Values 


Data Type 

Description 

int32 

0 D OK OK 


<0 D ERR Error 


Example 

Ret = ioctl (CmdFd, IFX_HAPI_DISPLAY_POWER_CTRL , IFX_HAPI_TRUE ) ; 


5.2.8 IFX_HAPI_DISPLAY_SET_CONTRAST 

Prototype 

Ret = ioctl (fd, IFX_HAPI_DISPLAY_SET_CONTRAST , ucValue); 

Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

1 FXH AP ID 1 SPLAY 
SETCONTRAST 

Controls the contrast of the display by changing the duty 
cycle of the PWM1 

1 

uint32 

ucValue 

Duty cycle value 

Possible values: 

Oh 

1 



FF h 



Return Values 


Data Type 

Description 

int32 

Always OK 
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Example 

uchar8 ucValue; 

ucValue = 100; /* duty cycle */ 

Ret = ioctl (CmdFd, IFX_HAPI_DISPLAY_SET_CONTRAST, ucValue) ; 

5.2.9 IFX_HAPI_DISPLAY_GET_CONTRAST 

Prototype 

Ret = ioctl (fd, IFX_HAPI_DISPLAY_GET_CONTRAST, 0); 

Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

IFX_HAPI_DISPL 

AYGETCONT 

RAST 

Gets the currently adjusted pulse width value (duty cycle) for 
contrast 

0 


Return Values 


Data Type 

Description 

int32 

>0 D CAP Currently adjusted pulse width value 
<0 D ERR Error 

Example 


int32 Ret; 



Ret = ioctl (CmdFd, IFX_HAPI_DISPLAY_GET_CONTRAST, 0); 

5.2.10 IFX_HAPI_DISPLAY_SET_BRIGHTNESS 
Prototype 

Ret = ioctl (fd, IFX_HAPI_DISPLAY_SET_BRIGHTNESS, ucValue); 

Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

IFX_HAPI_DISPL 

AY_SET_BRIGH 

TNESS 

Controls the brightness of the display by changing the duty 
cycle of the PWM2 

1 

uint32 

ucValue 

Duty cycle value 

Possible values: 

Oh 

1 



■■■H 

FF h 
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Data Type 

Description 

int32 

Always OK 

Example 


uchar8 

ucValue ; 


ucValue = 100; 

Ret = ioctl (CmdFd, IFX_HAPI_DISPLAY_SET_BRIGHTNESS , ucValue); 

5.2.1 1 IFX_HAPI_DISPLAY_GET_BRIGHTNESS 

Prototype 

Ret = ioctl (fd, IFX_HAPI_DISPLAY_GET_BRIGHTNESS, 0); 

Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

IFX_HAPI_DISPL 

AY_GET_BRIGH 

TNESS 

Gets the currently adjusted pulse width value (duty cycle) for 
brightness 

O 


Return Values 


Data Type 

Description 

int32 

>0 D CAP Currently adjusted pulse width value 
<0 D ERR Error 

Example 


int32 Ret; 



Ret = ioctl (CmdFd, IFX_HAPI_DISPLAY_GET_BRIGHTNESS , 0); 
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5.3 Keypad and Hook Status Event 

The following services operate on the command file descriptor: 

5.3.1 IFX_HAPI_GET_PHONE_EVENT 

Prototype 

Ret = ioctl (fd, IFX_HAPI_GET_PHONE_EVENT, pxPhoneEvent ) ; 

Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

1 FX_H AP l_G ET_ 
PHONEEVENT 

Gets the hook status or key pressed 

1 

x_IFX_HAPI_Phon 

eEvent 

‘pxPhoneEvent 

Pointer to a structure 

O 


Return Values 


Data Type 

Description 

int32 

0 D OK OK 


<0 D ERR Error 


Example 

x_IFX_HAPI_PhoneEvent xPhoneEvent ; 

fd_set xExceptFds; 

int iHapiFd, iSelMax; 
iHapiFd = open ( "/dev/hapi" , 0) 
iSelMax = iHapiFd; 

FD_ZERO (&xExceptFds) ; 

FD_SET ( f d, &xExceptFds ) ; 
do{ 

/* sleep till the arrival of an event */ 
select (iSelMax, NULL, NULL, &xExceptFds, NULL) ; 

/* got an event. now get the information */ 

if (ioctl (iHapiFd, IFX_HAPI_GET_PHONE_EVENT, &xPhoneEvent ) != 0) 

{ 

printf ( "GET_PHONE_EVENT failed\n" ) ; 
break; 

} 

if (xPhoneEvent. eEvent Type == IFX_HAPI_HOOK_STATUS) 

{ 

/* look for off hook or onhook */ 

} 

else 

{ 

/* key has been pressed */ 

} 
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} while (condition) ; 

5.4 Miscellaneous 

The following services operate on the command file descriptor: 

5.4.1 IFX_HAPI_MAP_SCANCODE_TO_DIGIT 

Prototype 

Ret = ioctl (fd, IFX_HAPI_MAP_SCANCODE_TO_DIGIT , pxCodeToDigit ) ; 

Parameters 


Data Type 

Name 

Description 

Dir 

uint32 

fd 

Command file descriptor 

1 

uint32 

IFX_HAPI_MAP_ 

SCANCODE_TO 

DIGIT 

Provides a mapping of key scan code to digit that is used for 
inband signaling 

1 

x_IFX_HAPI_Code 

ToDigit 

‘pxCodeToDigit 

Pointer to an array containing the scan codes 

1 


Return Values 


Data Type 

Name 

Description 

int32 

errorCode 

0 D OK OK 



<0 D ERR Error 


Example 

x_IFX_HAPI_CodeToDigit xCodeToDigit ; 

uchar8 ucScanCode [ 12 ] = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; 
uchar8 ucDigit[12] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; 
xCodeToDigit .ucSize = 10; 

memcpy (xCodeToDigit. ucScanCode, ucScanCode, 10); 
memcpy (xCodeToDigit . ucDigit , ucDigit, 10); 

Ret = ioctl (CmdFd, IFX_HAPI_MAP_SCANCODE_TO_DIGIT, &xCodeToDigit) ; 
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6 Type Definition Reference 


This chapter contains the type definitions related to the functional API. 


6.1 Basic Type Definitions 


This chapter contains the basic type definitions like: 

• int8 

• uint8 

• inti 6 

• uint16 

• int32 

• uint32 

• char8 

• uchar8 

6.1.1 int8 

Prototype 

typedef char int8; 

Parameters 


Data Type 

Name 

Description 

char 

int8 

This is the char 8-bit datatype 


6.1.2 uint8 


Prototype 

typedef unsigned char uint8; 

Parameters 


Data Type 

Name 

Description 

unsigned char 

uint8 

This is the unsigned char 8-bit datatype 


6.1.3 inti 6 


Prototype 

typedef short int uintl6; 

Parameters 


Data Type 

Name 

Description 

short int 

uint16 

This is the signed short integer 16-bit datatype 
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typedef unsigned short int uintl6; 
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Data Type 

Name 

Description 

unsigned short int 

uintl 6 

This is the unsigned short integer 16-bit datatype 


6.1.5 int32 

Prototype 

typedef int int32; 

Parameters 


Data Type 

Name 

Description 

int 

int32 

This is the int 32-bit datatype 


6.1.6 uint32 
Prototype 

typedef unsigned int uint32; 

Parameters 


Data Type 

Name 

Description 

unsigned int 

uint32 

This is the unsigned int 32-bit datatype 


6.1.7 char8 

Prototype 

typedef char char8; 

Parameters 


Data Type 

Name 

Description 

char 

char8 

This is the char 8-bit datatype 
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6.1.8 uchar8 


Prototype 

typedef unsigned char uchar8 ; 

Parameters 
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Data Type 

Name 

Description 

unsigned char 

uchar8 

This is the unsigned char 8-bit datatype 


6.2 Constants 

This section describes the Constants that are used. 


Table 5 Constants 


Name and Description 

Value 

IFX_HAPI_DISPLAY_MAXROW 

Maximum number of rows supported on the display 

4d 

IFX_HAPI_DISPLAY_MAXCOLUMN 

Maximum number of columns supported on the display 

20 d 

IFXHAPIDISPLAYLEFT 

Used to move display cursor to the left 

o D 

IFX_HAPI_DISPLAY_RIGHT 

Used to move display cursor to the right 

Id 

IFXHAPIDISPLAYHOME 

Used to move display cursor to the home position 

2d 

IFXHAPIDISPLAYNEXTLINE 

Used to move display cursor to the next line 

3d 

IFX_HAPI_DISPLAY_ROWHOME 

Used to move display cursor to the beginning of the row 

^d 

IFXHAPIDISPLAYPREVLINE 

Used to move display cursor to the previous line 

5 d 

IFX_HAPI_LED_ETH_SPD 

Allows Led multiplexer to use an LED for indicating ethernet speed 

01 H 

IFX_HAPI_LED_ETH_ACT 

Allows Led multiplexer to use an LED for indicating ethernet activity 

02 H 

IFXHAPILEDETHDPX 

LED ethernet duplex 

04 h 

IFX_HAPI_LED_ETH_STA 

Allows Led multiplexer to use an LED for indicating ethernet status 

08 H 

IFXHAPILEDETHTL 

When this bit is set, the LED (used for indicating ethernet activity) flashes when the data is 
transmitted and not when the data is received. But, when the bit is not set, the LED flashes 
when the data is received and not when the data is transmitted. 

10 H 

IFX_HAPI_HOOK_STATUS 

Indicates to the user that there is a hook status event 

0d 
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Table 5 Constants (cont’d) 

Name and Description 

Value 

IFX_HAPI_KEY_PRESSED 

Indicates to the user of the key press 

Id 

IFXHAPIKEYRELEASED 

Indicates to the user of the key release 

0d 


6.3 Structures 

This chapter lists all definitions and Structure codes. 


Table 6 Structures used 


Name 

Description 

x_IFX_HAPI_LEDEthCtrl 

Structure for Ethernet hardware configuration. 

xlFXHAPIMaxRowColumn 

Structure forgetting maximum row and column supported 
by the LCD device. 

xlFXHAPICursorPositon 

Structure for determining the row and column of the current 
cursor position. 

x_IFX_HAPI_DisplayGoTo 

Structure for determining the row and column position of 
the defined point in the display. 

xJFXHAPIDisplayPrint 

Structure for displaying a string at the current location. 

x_IFX_HAPI_PhoneEvent 

Structure for determining the hook and the key status. 

x_IFX_HAPI_Keylnfo 

Structure for querying on the key pressed. 

xlFXHAPICodeToDigit 

Structure for mapping of a key scan code to digit used for 
inband signaling. 


6.3.1 xlFXHAPILEDEthCtrl 

Description 

This is the data structure for Ethernet hardware configuration. 

Prototype 

typedef struct { 

int32 iEthPort; 
uchar8 ucEthLEDs ; 

} x_I FX_HAP I_LEDE the t r 1 ; 
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Parameters 


Data Type 

Name 

Description 

Dir 

int32 

iEthPort 

Defines the Ethernet port to which the access is applied. 

0 D ETHPC IFX_HAPI_LED_ETHPORT_PC 

1 D ETHLAN 1 FXHAP l_LE DETH PO RTLAN 

1 

uchar8 

ucEthLEDs 

Defines all the special function LED's that are controlled by 
Ethernet hardware (lower 5 bits) 

This is the logical OR of: 

1 D ETHSPD 1 FX_H AP l_LE D_ETH_S P D 

2 d ETH_ACT IFX_HAPI_LED_ETH_ACT 

4 d ETH_DPX IFX_HAPI_LED_ETH_DPX 

8 d ETH_STA IFX_HAPI_LED_ETH_STA 

16 d ETH_TL IFX_HAPI_LED_ETH_TL 

1 


6.3.2 x_IFX_HAPI_MaxRowColumn 

Description 

This is the data structure for getting maximum row and column supported by the LCD device. 

Prototype 

typedef struct { 

uchar8 ucMaxRow; 
uchar8 ucMaxColumn; 

} x_IFX_HAPI_MaxRowColumn; 

Parameters 


Data Type 

Name 

Description 

Dir 

uchar8 

ucMaxRow 

Maximum row number 

0 

uchar8 

ucMaxColumn 

Maximum column number 

0 


6.3.3 xlFXHAPICursorPositon 


Description 

This is the data structure for determining the row and column of the current cursor position. 

Prototype 

typedef struct { 

uchar8 ucRow; 
uchar8 ucColumn; 

} x_IFX_HAPI_CursorPositon; 
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Data Type 

Name 

Description 

Dir 

uchar8 

ucRow 

Row number 

1 

uchar8 

ucColumn 

Column number 

1 


6.3.4 x_IFX_HAPI_DisplayGoTo 

Description 

This is the data structure for determining the row and column position of the defined point in the display. 

Prototype 

typedef struct { 

uchar8 ucRow; 
uchar8 ucColumn; 

} x_IFX_HAPI_DisplayGoTo; 

Parameters 


Data Type 

Name 

Description 

Dir 

uchar8 

ucRow 

Row number of new cursor position 

(between 0 and MAX_ROW). 

1 

uchar8 

ucColumn 

Column number of new cursor position 

(between 0 and MAX_COL). 

1 


6.3.5 x_IFX_HAPI_DisplayPrint 

Description 

This is the data structure for displaying a string at the current location. 

Prototype 

typedef struct { 

int32 iNumber; 
char8 szString; 

}x_IFX_HAPI_DisplayPrint ; 

Parameters 


Data Type 

Name 

Description 

Dir 

int32 

Number 

Number of characters to be printed 

1 

char8* 

szString 

String to be printed 

1 
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6.3.6 x_IFX_HAPI_PhoneEvent 

Description 

This is the data structure for determining the hook and the key status. 

Prototype 

typedef struct { 

uchar8 eEventType ; 

uni on { 

uchar8 ucHookStatus; 

x_IFX_HAPI_KeyInfo xKeylnfo; 

} uxEventType ; 

}x_IFX_HAPI_PhoneEvent ; 

Parameters 
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Data Type 

Name 

Description 

Dir 

uchar8 

eEventType 

Event Type can be either of the following 

O 



0 D HO_STA 1 FX_H AP l_H 00 K_ST ATU S 




1 D KEY PRE IFX_HAPI_KEY_PRESSED 


uxEventType 


Union of ucHookStatus and xKeylnfo 

O 


uxEventType 

union { 

uchar8 HookStatus ; 

x_IFX_HAPI_KeyInfo xKeylnfo; 

} uxEventType 


Data type 

Name 

Description 

Dir 

uchar8 

HookStatus 

Status of the hook can be either of the following 

0 D ONHO IFX_HAPI_ON_HOOK 

1 D OFFHO IFX_HAPI_OFF_HOOK 

O 

x_IFX_HAPI_Keyln 

fo 

xKeylnfo 

Structure of ucKey and uiDuration 

O 


6.3.7 x_IFX_HAPI_Keylnfo 

Description 

This is the data structure for querying on the key pressed. 

Prototype 

typedef struct { 

uchar8 ucKey; 
uint32 uiDuration; 
uint32 ucState ; 

} x_IFX_HAPI_KeyInfo 


Preliminary User’s Manual 
Programmer’s Reference 


34 


Revision 


2007-06-20 


'Infineon 


CONFIDENTIAL 


EASY 21653 INCA-IP2 
VoIP IPP Subsystem 


Type Definition Reference 


Data Type 

Name 

Description 

Dir 

uchar8 

ucKey 

Scan code of the key pressed 

0 

uint32 

uiDuration 

Duration for which the key was pressed 

0 

uint32 

ucState 

State of the key. It can have either of the following values: 

• HAPI_KEY_RELEASED 

• HAPI_KEY_PRESSED 

0 


6.3.8 x_IFX_HAPI_CodeToDigit 


Description 

This is a structure for mapping of a key scan code to digit used for inband signaling. 

Prototype 

typedef struct { 

uchar8 ucSize; 
uchar8 ucScanCode [ ] ; 
uchar8 ucDigit[ ]; 

} x_IFX_HAPI_CodeToDigit ; 

Parameters 


Data Type 

Name 

Description 

Dir 

uchar8 

ucSize 

Size of the scan code and the digit buffers 

Note: The size of the scan code and the digit buffers should be the 
same. 

1 

uchar8 

ucScanCode 

Array of scan codes 

1 

uchar8 

ucDigit 

Array of digits 

1 
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